home *** CD-ROM | disk | FTP | other *** search
/ Power Tools 1993 October - Disc 2 / Power Tools (Disc 2)(October 1993)(HP).iso / hotlines / ccsyhl / sisaparc / sisaparc.txt
Text File  |  1993-05-21  |  15KB  |  328 lines
  1. HP Software Integration Sockets
  2. Adapter Architecture
  3.  
  4.  
  5. 1.0     Introduction
  6.  
  7. HP Software Integration Sockets Adapter Architecture describes a robust
  8. architec ture for writing a flexible full functioned HP Sockets adapter
  9. for your application. The rest of this document defines the functional
  10. overview of a "receive" a dapter and the configuration mechanism for
  11. the messages the adapter receives, a short overview of a "send"
  12. adapter, and a description of two adapters available for you to test
  13. your adapter under development.
  14.  
  15. 2.0     Architecture Philosophy
  16.  
  17. To help you get started more quickly on your HP Sockets adapter, we
  18. have defined general "receive" and "send" adapter architectures that
  19. have been successfully used to create application adapters. In addition
  20. to giving you a general flow to follow, if your adapter conforms to
  21. this outline it will be configurable and plug ready for an HP Sockets-
  22. based integrated solution.
  23.  
  24. 3.0     "Receive" Adapter Architecture
  25.  
  26. The functional flow of a "receive" adapter should be:
  27.  
  28. 1. Initialize any global variables, path names, etc.
  29.  
  30. 2. Initialize a signal for the stop routine.  This will make sure
  31. communication with HP Sockets is terminated gracefully when the
  32. interrupt signal is received to stop the adapter.
  33.  
  34. 3. Read in the adapter\xd5s configuration file. This is a file separate
  35. from the six HP Sockets configuration files. The purpose of this file
  36. is to define in one place the types of transactions the adapter can
  37. receive and the output form at strings to convert the incoming message
  38. data into a command for the application.
  39.  
  40. 4. Initialize communication between the adapter and HP Sockets.
  41.  
  42. 5. Process incoming messages in an infinite loop:
  43.  
  44. Extract the message type, function and data items from the message. Get
  45. the transaction entry for the message from the adapter's configuration
  46. information. Use the output format strings from the configuration to
  47. format the message data which is written to the output buffer. Send the
  48. output buffer to the application using its data import mechanisms.
  49.  
  50. Throughout this flow, status and error messages are written to a log
  51. file (named XXX.lg where XXX is the name of the adapter). The following
  52. diagram illustrates this functional flow.
  53.  
  54.  
  55.  
  56.  
  57.  
  58. 3.1     Incoming Messages
  59.  
  60. All incoming messages to a "receive" adapter must follow the standard
  61. message format described in HP Software Integration Sockets Standard
  62. Message Format. These messages consist of a single ASCII string with
  63. fields separated by a configurable delimiter. All adapters should
  64. define the constant INPUT_DATA_DELIM to be the particular delimiter
  65. character. When an integrated solution is being created by plugging
  66. various adapters together, the delimiter can be changed by altering the
  67. value of the constant in each of the adapters and re-compiling. All
  68. adapters in an HP Sockets- based integrated solution must be using the
  69. same delimiter to interoperate. The Request messages (message type
  70. REQM) and Sent messages (message type SENTM) to be handled by a
  71. "receive" adapter are defined in its configuration file which is
  72. described in section 3.3.
  73.  
  74. 3.2     Message Sequencing
  75.  
  76. In the case of a multiple message transaction, we want to be sure not
  77. to intersperse messages from different transactions within the
  78. "receive" adapter. To do this, the main SpReadQ call reads an incoming
  79. message from any adapter (that is, it uses a NULL ProcessLn parameter).
  80. If the message is the first in a multiple message transaction, a
  81. subsequent SpReadQ call is made to read messages only fro m the adapter
  82. that sent the first message in the transaction (by setting the
  83. ProcessLn parameter to the name of the adapter that sent the first
  84. message). After the final message in the transaction is received, the
  85. adapter returns to reading messages from any adapter.
  86.  
  87. 3.3      Adapter Configuration File
  88.  
  89. The adapter configuration file defines the transactions that the
  90. adapter can per form. It is an ASCII file that is read into memory when
  91. the adapter is started. Its purpose is to provide a way to configure
  92. the adapter without having to hardcode the various transactions it
  93. supports. The configuration file can contain comments and transaction
  94. entries. Comments start with a # in column 0. All other lines are
  95. assumed to be part of a transaction entry. This file is generally named
  96. XXX.config where XXX is the name of the adapter.
  97.  
  98. The general format of a transaction entry in the adapter configuration
  99. file is:
  100.  
  101.      # Comments start with a # in column 0.  No blank lines are
  102.      allowed.  #
  103.      FunctionName NumberOfHeaderLines NumberOfRepeatLines
  104.      FinalFunctionName
  105.      "HeaderMessageFormatLines" "RepeatMessageFormatLines"
  106.      "EndMessageFormatLines"
  107.  
  108.  
  109. Each transaction entry consists of the following information:
  110.  
  111.         Function Name -  the name for this transaction entry.  The
  112. value of the Function field (the second field) in the standard message
  113. format will be matched with this name to choose the correct entry.
  114.  
  115.         Final Function Name - the Function Name that will appear in the
  116. final message if this is a multiple message transaction. It must begin
  117. with a capital letter in the configuration file. This field is not
  118. required if the transaction consists of a single message. Message
  119. format lines - instructions for how to format the data received in the
  120. message to create a command to send to the application. It consists of
  121. three types of format lines to give you the most flexibility in
  122. adapting to the input syntax of the application you are writing the
  123. adapter for. Each format line is similar in syntax to the C printf
  124. function format stringand is enclosed within double quotes. The string
  125. can contain literal ASCII characters which are passed through to the
  126. output unchanged plus the following special formatting characters which
  127. are replaced with data from the incoming message before being output.
  128. The special format characters are:
  129.  
  130.          -  ^ - replaced with a new line -  %f - replaced with the
  131.          Function from the message -  %r - replaced with the Adapter
  132.          Name from the message -  %xx - replaced by a function specific
  133.          field from the message where xx is an integer representing
  134.          which function specific field.  %0 is replaced by the
  135.          first field, %1 by the second field, etc.
  136.  
  137. The three types of format lines are:
  138.  
  139.         Header Message Format Lines - use for the opening part of the
  140. command. These header lines are output at the beginning of the
  141. transaction when the first message is received.
  142.  
  143.         Repeat Message Format Lines - use for the data in the command.
  144. These repeat lines are output for each message in a transaction except
  145. for the final message.
  146.  
  147.         End Message Format Lines - use for the closing part of the
  148. command. These end lines are output at the end of the transaction when
  149. the final message in the transaction is received.
  150.  
  151. Number Of Header Lines - how many of the message format lines in this
  152. transaction entry are header lines.
  153.  
  154. Number Of Repeat Lines - how many of the message format lines following
  155. the header lines are repeat lines.
  156.  
  157. The general format of a transaction entry in the adapter configuration
  158. file is:
  159.  
  160.      # Comments start with a # in column 0.  No blank lines are
  161.      allowed.  #
  162.      FunctionName NumberOfHeaderLines NumberOfRepeatLines
  163.      FinalFunctionName
  164.      "HeaderMessageFormatLines" "RepeatMessageFormatLines"
  165.      "EndMessageFormatLines"
  166.  
  167. 3.3.1   Example
  168.  
  169. Here is a sample entry in an adapter configuration file:
  170.  
  171.      # Entry for Function Func Func 1 1 FuncEND
  172.      "@@batchload func.p^" "%f^%0 %2 %1 %r^"
  173.      ".^@@end^"
  174.  
  175. If the three following input messages are received by the adapter:
  176.  
  177.      SENTM|Func|process1|1.0|2.3|4.5|
  178.      SENTM|Func|process1|2.3|6.7|9.8|
  179.      SENTM|FuncEND|process1|
  180.  
  181. The  individual message fields for the first message would be parsed
  182. as:
  183.  
  184.         Message Type = SENTM Function = Func
  185.         Adapter Name = process1 Data0 = 1.0 Data1
  186.         = 2.3 Data2 = 4.5
  187.  
  188. And the resulting output format lines would be the following:
  189.  
  190. @@batchload func.p                              <---
  191.       header line "Func"
  192.       <--- repeat line "1.0" "4.5" "2.3" "process1"
  193.      "Func"
  194.      <--- repeat li ne
  195.      "2.3" "9.8" "6.7" "process1" .
  196.      <--- end
  197. line @@end                                               <--- end line
  198.  
  199.  
  200. 4.0     "Send" Adapter Architecture
  201.  
  202. A "send" adapter is started only when there is data to send from the
  203. adapter's application to another application. When the adapter is
  204. started, it gets the data from the application, formats it into the
  205. standard message format, sends the message(s) using HP Sockets and the
  206. SpSendMsg access routine, and stops.
  207.  
  208. 5.0     Test Adapters
  209.  
  210. Two HP Sockets adapters have been written to help you test your adapter
  211. under development if it uses the standard message format described in
  212. HP Software Integration Sockets Standard Message Format. The two
  213. adapters are send_test and recv_ test. Send_test allows you to easily
  214. enter all of the elements of an HP Sockets message, along with the name
  215. of the destination adapter. It then formats the input data into an HP
  216. Sockets message, sends the message to the adapter being tested, and
  217. writes a copy of the message to its log file, send_test.lg. You may
  218. optionally specify the name of an adapter to be started to capture the
  219. return message from the adapter under test. Recv_test is an optional
  220. adapter to use to capture the return message, display it on the screen,
  221. and write it to its log file (recv_test.lg) for further review.
  222.  
  223. 5.1     How to use them
  224.  The adapter under test, the send_test and recv_test adapters, and
  225. their log files must all be in the same directory. The environment
  226. variable ADAPTOR_PATH must be set to the full path name of this
  227. directory. To start send_test simply type send_test. You will then be
  228. prompted for the following items. The previously entered value for that
  229. prompt is always displayed. If you wish to retain the same value,
  230. simply hit the carriage return (<cr>) to keep that value.
  231.  
  232.  1. Return Adapter Name - This is the name of the adapter that should
  233. be started to capture any messages generated in response to the message
  234. sent to the adapter under test. Typically this would be the adapter
  235. recv_test. This is only entered once for each invocation of send_test.
  236. This is an optional item. If your test adapter does not generate return
  237. messages, or you do not wish to receive them , just enter <cr> at this
  238. prompt.
  239. 2. Message Type - This is the message type field of the HP Sockets
  240. standard mess age format. Enter one of REQM, SENTM, or ERROR. Enter
  241. ENDENDEND to stop send _test.
  242. 3. Function Name - This is the Function field of the HP Sockets
  243. standard message format. It should be one of the Functions the adapter
  244. under test understands.
  245. 4. Adapter Name - The name of this test adapter. This is used in the
  246. SpInit call to initialize communication between the send_test process
  247. and HP Sockets. Use a name that is configured in your Process
  248. Definition file.
  249. 5. Destination Adapter Name - The name of the adapter the message is to
  250. be sent to -  the adapter under test.
  251. 6. Data Items - Up to 10 data items that are the function specific data
  252. for the Function.  The order of the entries is significant since they
  253. are used to replace the %xx parameters in the configuration message
  254. format lines.  If you wish to skip a data item, simply hit <cr>.  The
  255. send_test adapter can be modified to ask for more than 10 data items if
  256. your adapter under test requires that.
  257.  
  258. After entering all of the data, it will be displayed and you will be
  259. asked if it is correct. If so, enter Y <cr> and the message will be
  260. formatted, sent to the destination adapter, and written to the log
  261. file. If it is incorrect, enter N <cr>, you will get a chance to
  262. correct all of the values. Simply hit <cr> for the items that are
  263. already correct.
  264.  
  265. After the message is sent, you will be back at the prompt for the
  266. Message Type. Enter the data for the next test message or ENDENDEND to
  267. stop the program.
  268.  
  269. 6.0     Sample Code
  270.  
  271. A sample receive and send adapter is available along with the source
  272. code to the send_test and recv_test adapters. Contact the HP Sockets
  273. Program to receive a tape. The tape contains the following files:
  274.  
  275.      makefile - Run "make" to use this file to create all four of the
  276. sample adapter s.
  277.  
  278.      MRP.c - Source code to the MRP "receive" adapter. Test this
  279. adapter with the s end_test program. Start MRP and then start send_test
  280. answering the questions it asks about the message you want to send to
  281. MRP. Here is a sample script for th e send_test adapter to send a
  282. message to MRP:
  283.  
  284.         Enter the optional RETURN ADAPTOR name or <cr> (): <cr> Enter
  285.         the MESSAGE type (): REQM Enter the FUNCTION name (): OpParts
  286.         Enter this ADAPTOR\xd5s name (): send_test Enter the
  287.         DESTINATION ADAPTOR name (): MRP Enter DATA ITEM #0 (): 1 Enter
  288.         DATA ITEM #1 (): 2 Enter DATA ITEM #2 (): 3 Enter DATA ITEM #3
  289.         (): 4 Enter DATA ITEM #4 (): 5 Enter DATA ITEM #5 (): 6 Enter
  290.         DATA ITEM #6 (): 7 Enter DATA ITEM #7 (): 8 Enter DATA ITEM #8
  291.         (): 9
  292.  
  293.         MESSAGE type                   : REQM FUNCTION name
  294.         : OpParts ADAPTOR name                  : send_test
  295.         DESTINATION ADAPTOR : MRP DATA ITEM #0                    :
  296.         1 DATA ITEM #1                    : 2 DATA ITEM #2
  297.         : 3 DATA ITEM #3                    : 4 DATA ITEM #4
  298.         : 5 DATA ITEM #5                    : 6 DATA ITEM #6
  299.         : 7 DATA ITEM #7                    : 8 DATA ITEM #8
  300.         : 9
  301.  
  302.         Are these data values correct? (y/n): y Output buffer
  303.         from send_test is: REQM|OpParts| |1|2|3|4|5|6|7|8|9
  304.  
  305. And the corresponding output from MRP when it receives this message is:
  306.  
  307.                 @@batchload cmdc.p "OpParts" "1" "2"
  308.                 ""      .  @@end
  309.  
  310.         MRP.config - Adapter configuration file for the MRP adapter.
  311. It defines all of the transactions the adapter can process.
  312.  
  313.         MRPSEND.c - Source code to the MRP "send" adapter.
  314.  
  315.         recv_test.c - Source code to the receive test adapter.
  316.  
  317.         send_test.c - Source code to the send test adapter.
  318.  
  319. Netw.def - Network Definition file containing a configuration that will
  320. run the MRP, send_test, and recv_test adapters.  Alter this file so it
  321. reflects the correct networking information for the machine you are
  322. running these adapters on.
  323.  
  324. Proc.def - Process Definition file containing a configuration that will
  325. run the MRP, send_test, and recv_test adapters. Alter this file if you
  326. change the logical node name of the machine the adapters will run on or
  327. if you change the logical name of any of the adapters.
  328.